オプション解析モジュール click を使いこなそう

click について

ClickはFlaskマイクロフレームワークの基礎として使用されたPython Web開発ライブラリのコレクションのひとつで、オプション解析処理をしてくれる拡張モジュールです。

Command-Line Interface Creation Kit から命名されています。

click は拡張モジュールなのでインストールする必要があります。

conda コマンドは 実行環境によっては pip コマンドを使う場合もあります。

code: conda

$ conda install click

code: pip

$ pip install click

click.echo()

code: click_echo.py

@click.command()

def cmd():

typer.echo("This message oputput to stdout.")

typer.echo("This message oputput to stderr.", err=True)

if __name__ == '__main__':

cmd()

code: bash

% python typer_echo.py

This message oputput to stdout.

This message oputput to stderr.

% python typer_echo.py 2>/dev/null

This message oputput to stdout.

click.style()

click.sytle(text, fg, bg, bold, dim, underline, blink, reverse, reset)

text: 任意の文字列

fg: 前景色/文字の色 ('red', 'green', 'yellow'など)

bg: 背景色

bold: ボールド表示

dim: 薄暗く表示する

underline: アンダーライン表示

blink: 点滅表示

reverse: 前景色、背景色の反転

reset: 設定のリセット、False にすると設定を引き継ぐ

code: click_style.py

import click

@click.command()

def cmd():

click.echo(click.style('Hello World.',

fg='green', bg='red', reset=False))

click.echo(click.style('Hello Again.'))

if __name__ == '__main__':

cmd()

click.launch()

code: click_launch.py

import click

def open_google():

click.echo("Opening Google...")

if __name__ == "__main__":

open_google)

オプション解析

code: click_hello.py

import click

@click.command()

@click.option('-C', '--count', default=1, help='Number of greetings.')

@click.option('--name', prompt='Your name', help='The person to greet.')

def hello(count, name):

"""COUNTで与えた回数だけHelloする"""

for x in range(count):

click.echo(f'Hello {name}')

if __name__ == '__main__':

hello()

code: bash

$ python click_hello.py --help

COUNTで与えた回数だけHelloする

Options:

-C, --count INTEGER Number of greetings.

--name TEXT The person to greet.

--help Show this message and exit.

$ python click_hello.py

Your name: Jack

Hello Jack!

$ python click_hello.py --name='David'

Hello David!

$ python click_hello.py --count=2

Your name: Freddie

Hello Freddie!

Hello Freddie!

関数に記述した docstrings がヘルプ表示のときに使用されます。

デコレートされる関数を次のようにすると辞書として受け取ることができます。

code: click_hello2.py

import click

@click.command()

@click.option('-C', '--count', default=1, type=int, help='Number of greetings.')

@click.option('--name', prompt='Your name', type=str, help='The person to greet.')

def hello(**kwargs):

print(kwargs)

hello()

code: bash

$ python click_hello2.py

Your name: Feddie

{'count': 1, 'name': 'Feddie'}

オプションをフラグとして処理したい

code: click_optflag.py

import click

@click.command()

@click.option('--debug', is_flag=True, help='DEBUG mode')

def cmd(debug):

click.echo( f'DEBUG mode {debug}')

if __name__ == '__main__':

cmd()

code: bash

$ python click_optflag.py --help

Options:

--debug DEBUG mode

--help Show this message and exit.

$ python click_optflag.py

DEBUG mode False

$ python click_optflag.py --debug

DEBUG mode True

オプション引数を可変長にする

code: click_optmultiargs.py

import click

@click.command()

@click.option('-P', '--position', nargs=2, help='Geometory: X y')

def cmd(position):

click.echo( position )

if __name__ == '__main__':

cmd()

code: bash

$ python click_optmultivalue.py -P 1

Error: -P option requires 2 arguments

$ python click_optmultivalue.py -P 1 2

('1', '2')

$ python click_optmultivalue.py -P 1 2 3

Try "click_optmultivalue.py --help" for help.

Error: Got unexpected extra argument (3)

同じオプションを複数回指定することを許す

code: click_multiopt.py

import click

@click.command()

@click.option('-m', '--message', multiple=True)

# @click.option('-m', '--message')

def cmd(message):

click.echo( message )

if __name__ == '__main__':

cmd()

code: bash

$ python click_multiopts.py -m Beer -m Wine

('Beer', 'Wine')

オプションが指定された回数を知りたい

code: click_optcount.py

import click

@click.command()

@click.option('-v', '--verbose', count=True, help='Verbosly Mode')

def cmd(verbose):

click.echo(f'verbose level: {verbose}')

if __name__ == '__main__':

cmd()

code: bash

$ python click_optcount.py

verbose level: 0

$ python click_optcount.py -v

verbose level: 1

$ python click_optcount.py -v -v

verbose level: 2

$ python click_optcount.py -vvvv

verbose level: 4

オプション引数を限定させたい

code: click_optchoice.py

import click

@click.command()

def cmd(hash_type):

click.echo( hash_type )

if __name__ == '__main__':

cmd()

code: bash

$ python click_optchoice.py --help

Options:

--help Show this message and exit.

$ python click_optchoice.py -H md5

md5

$ python click_optchoice.py -H sha1

sha1

$ python click_optchoice.py -H sha256

Try "click_optchoice.py --help" for help.

Error: Invalid value for "-H" / "--hash-type": invalid choice: sha256. (choose from md5, sha1)

オプション引数の数値範囲を指定したい

code: click_optrange.py

import click

max_cpus=8

@click.command()

@click.option('-N', '--ncpus', type=click.IntRange(1,max_cpus,clamp=True),

help=f'Set cpu numbers. (1...{max_cpus})')

def cmd(ncpus):

click.echo( ncpus )

if __name__ == '__main__':

cmd()

code: bash

$ python click_optrange.py --help

Options:

-N, --ncpus INTEGER RANGE Set cpu numbers. (1...8)

--help Show this message and exit.

$ python click_optrange.py -N 8

8

$ python click_optrange.py -N 10

8

$ python click_optrange.py -N -2

1

オプションでUUIDを扱いたい

code: click_optuuid.py

import click

@click.command()

@click.option("--uuid", type=click.UUID, required=True)

def cmd(uuid):

click.echo(f'UUID={uuid}')

if __name__ == '__main__':

cmd()

code: bash

$ python click_optuuid.py --help

Options:

--help Show this message and exit.

$ python -c "import uuid; print(uuid.uuid4())"

7c02d20d-2ef6-497f-a4d2-ea19a666ef6d

$ python click_optuuid.py --uuid=7c02d20d-2ef6-497f-a4d2-ea19a666ef6d

uuid=7c02d20d-2ef6-497f-a4d2-ea19a666ef6d

$ python click_optuuid.py --uuid=7c02d20d-2ef6-497f-a4d2-ea19a666

Try "click_optuuid.py --help" for help.

Error: Invalid value for "--uuid": 7c02d20d-2ef6-497f-a4d2-ea19a666 is not a valid UUID value

オプションのプレフィックスを変更したい

code: click_optprefix.py

import click

@click.command()

@click.option('+w/-w', default=True)

def cmd(w):

click.echo( 'writable=%s' % w )

if __name__ == '__main__':

cmd()

code: bash

$ python click_optprefix.py --help

Options:

+w / -w

--help Show this message and exit.

$ python click_optprefix.py

writable=True

$ python click_optprefix.py -w

writable=False

$ python click_optprefix.py +w

writable=True

Windowsスタイルのオプシン

code: click_optwinstyle.py

import click

@click.command()

@click.option('/debug;/no-debug')

def cmd(debug):

click.echo( 'debug=%s' % debug )

if __name__ == '__main__':

cmd()

オプション解析時にコールバック関数を与えたい

code: click_optcallback.py

import click

def print_version(ctx, param, value):

if not value or ctx.resilient_parsing:

return

click.echo('Version 1.0')

ctx.exit()

@click.command()

@click.option('--version', callback=print_version,

is_flag=True, expose_value=False, is_eager=True)

def cmd():

click.echo('command was done.')

if __name__ == '__main__':

cmd()

コールバック関数でオプションで指定された値のチェックを行うといった処理に使用します。

code: cick_optcallback_validate.py

import click

def validate_rolls(ctx, param, value):

try:

rolls, dice = map(int, value.split('d', 2))

return (dice, rolls)

except ValueError:

raise click.BadParameter('rolls need to be in format NdM')

@click.command()

@click.option('--rolls', callback=validate_rolls, default='1d6')

def roll(rolls):

if __name__ == '__main__':

roll()

確認を求めるようなオプション処理

コールバック関数を使うと確認を求めてようなオプションを作ることができます。

code: click_optcallback_yesno.py

import click

def abort_if_false(ctx, param, value):

if not value:

ctx.abort()

@click.command()

@click.option('--yes', is_flag=True, callback=abort_if_false,

expose_value=True,

prompt='Are you sure you want to drop the db?')

def cmd(yes):

click.echo('Dropped all tables!')

if __name__ == '__main__':

cmd()

code: click_confirm.py

import click

@click.command()

@click.confirmation_option(prompt='Are you sure you want to drop the db?')

def cmd():

click.echo('Dropped all tables!')

if __name__ == '__main__':

cmd()

パスワード入力の処理をしたい

code: click_optpassword.py

import click

@click.command()

@click.option('--password', prompt='Password',

hide_input=True, confirmation_prompt=True)

def cmd(password):

click.echo( password )

if __name__ == '__main__':

cmd()

code: click_passwordsmart.py

import click

@click.command()

@click.password_option()

def cmd(password):

click.echo( password )

if __name__ == '__main__':

cmd()

コマンド引数を処理したい

code: click_argument.py

import click

@click.command()

@click.argument('src', nargs=-1, required=True)

@click.argument('dst', nargs=1)

def copy(src, dst):

"""Move file SRC to DST."""

for filename in src:

click.echo(f'move {filename} to folder {dst}')

if __name__ == '__main__':

copy()

コマンド引数をファイルとして扱いたい

code:click_argument_as_file.py

import click

@click.command()

@click.argument('srcfile', type=click.File('r'))

def cmd(srcfile):

lines = srcfile.readlines()

for line in lines:

if __name__ == '__main__':

cmd()

code: bash

$ python click_argument_as_file.py /tmp/junk.txt

Try "click_argument_as_file.py --help" for help.

Error: Invalid value for "SRCFILE": Could not open file: /tmp/junk.txt: No such file or directory

$ echo 'Think Big.' > /tmp/junk.txt

$ python click_argument_as_file.py /tmp/junk.txt

Think Big.

code: click_argument_as_filepath.py

import click

@click.command()

@click.argument('srcfile', type=click.Path(exists=True))

def cmd(srcfile):

print(type(srcfile))

click.echo( click.format_filename(srcfile) )

if __name__ == '__main__':

cmd()

code: bash

$ python click_argument_as_filepath.py /tmp/junk.txt

<class 'str'>

/tmp/junk.txt

$ rm /tmp/junk.txt

$ python click_argument_as_filepath.py /tmp/junk.txt

Try "click_argument_as_filepath.py --help" for help.

Error: Invalid value for "SRCFILE": Path "/tmp/junk.txt" does not exist.

コマンド引数を環境変数でも指定できるようにしたい

code: click_argument_envvar.py

import click

@click.command()

@click.argument('srcfile', envvar='SRCFILE', type=click.Path(exists=True))

def cmd(srcfile):

print(type(srcfile))

click.echo( click.format_filename(srcfile) )

if __name__ == '__main__':

cmd()

code: bash

$ echo 'Think Big.' > /tmp/junk.txt

$ python click_argument_envvar.py /tmp/junk.txt

<class 'str'>

/tmp/junk.txt

$ export SRCFILE=/tmp/junk.txt

$ python click_argument_envvar.py

<class 'str'>

/tmp/junk.txt

$ unset SRCFILE

$ python click_argument_envvar.py

Try "click_argument_envvar.py --help" for help.

Error: Missing argument "SRCFILE".

サブコマンド処理

code: click_subcommand.py

import click

@click.group()

def cli():

pass

@click.command()

def initdb():

click.echo('Initialized the database')

@click.command()

@click.option('--force', is_flag=True, default=True,

help='drop db anyway')

@click.argument('dbname')

def dropdb(force, dbname):

click.echo(force)

click.echo(f'Droped the database: {dbname}')

cli.add_command(initdb)

cli.add_command(dropdb)

if __name__ == "__main__":

cli()

code: bash

$ python click_subcommand_option.py

Options:

--help Show this message and exit.

Commands:

dropdb

initdb

$ python click_subcommand_option.py initdb

Initialized the database

$ python click_subcommand_option.py dropdb

Try "click_subcommand_option.py dropdb --help" for help.

Error: Missing argument "NAME".

$ python click_subcommand_option.py dropdb --help

Options:

--force drop db anyway

--help Show this message and exit.

$ python click_subcommand_option.py dropdb sample

True

Droped the database:sample

処理中にプログレスバーを表示させたい

code: click_progressbar.py

import click

import math

import time

import random

@click.command()

@click.option('--count', default=8000, type=click.IntRange(1, 100000),

help='The number of items to process.')

def cmd(count):

"""Demonstrates the progress bar."""

items = range(count)

def process_slowly(item):

time.sleep(0.002 * random.random())

def filter(items):

for item in items:

if random.random() > 0.3:

yield item

with click.progressbar(items, label='Processing accounts',

fill_char=click.style('#', fg='green')) as bar:

for item in bar:

process_slowly(item)

def show_item(item):

if item is not None:

with click.progressbar(filter(items), label='Committing transaction',

fill_char=click.style('#', fg='yellow'),

item_show_func=show_item) as bar:

for item in bar:

process_slowly(item)

with click.progressbar(length=count, label='Counting',

bar_template='%(label)s %(bar)s | %(info)s',

fill_char=click.style(u'█ ', fg='cyan'),

empty_char=' ') as bar:

for item in bar:

process_slowly(item)

with click.progressbar(length=count, width=0, show_percent=False,

show_eta=False,

fill_char=click.style('#', fg='magenta')) as bar:

for item in bar:

process_slowly(item)

# 'Non-linear progress bar'

count = int(sum(steps))

with click.progressbar(length=count, show_percent=False,

label='Slowing progress bar',

fill_char=click.style(u'█ ', fg='green')) as bar:

for item in steps:

time.sleep(item)

bar.update(item)

if __name__ == '__main__':

cmd()

オプション解析処理の情報を関数に渡したい

code: click_passcontext.py

import click

@click.group()

@click.option('--debug/--no-debug', default=False)

@click.pass_context

def cli(ctx, debug):

@cli.command()

@click.pass_context

def sync(ctx):

if __name__ == '__main__':

cli(obj={})

click アプリケーションのテスト

code: click_hello.py

import click

@click.command()

@click.option('-C', '--count', default=1, help='Number of greetings.')

@click.option('--name', prompt='Your name', help='The person to greet.')

def hello(count, name):

"""COUNTで与えた回数だけHelloする"""

for x in range(count):

click.echo(f'Hello {name}')

if __name__ == '__main__':

hello()

これをテストするためのコードは次のようになります。

code: test_click_hello.py

from click.testing import CliRunner

from click_hello import hello

def test_hello():

runner = CliRunner()

result = runner.invoke(hello, '--name Peter')

assert result.exit_code == 0

assert result.output == 'Hello Peter!\n'

result = runner.invoke(hello, '--name Jack -C 2')

assert result.exit_code == 0

assert result.output == 'Hello Jack!\nHello Jack!\n'

if __name__ == '__main__':

test_hello()

参考：